Skip to content

Refresh the docs against what N-11 actually shipped - #110

Merged
kiwifellows merged 2 commits into
developfrom
docs/refresh-after-n11
Aug 3, 2026
Merged

Refresh the docs against what N-11 actually shipped#110
kiwifellows merged 2 commits into
developfrom
docs/refresh-after-n11

Conversation

@kiwifellows

Copy link
Copy Markdown
Contributor

What and why

First staleness check on user-docs/, three days after it was written and immediately after N-11 phase 2, #100 and #102 landed. Two pages had already drifted — both making claims about things that changed underneath them.

This is the maintenance pass the docs conventions were built to make cheap. It found real drift on the first run.

What was stale

The architecture page said the quick-create link carries four parameters. It carries five — N-11 phase 2 added TopsInstallId, and the parent subscription now only forwards messages carrying that value, quarantining the rest. That is a materially better story for the security reviewers this page is written for, so it now describes the filter and the quarantine queue rather than just correcting a count.

SECURITY.md listed three known issues, two of them now closed. #100 shipped and #102's template is deleted. A vulnerability policy telling researchers not to report things that are already fixed is worse than useless — it discourages reporting a regression. #101 stays, reworded to describe what is now in place rather than what was open when it was written. #109 takes the freed slot, with an honest note that the SQS:ReceiveMessage grant is dead permission rather than exposure.

What was verified and did not need changing

Checked rather than assumed, against the current tree:

Claim Source Result
21 inline policies, 3 resource-scoped, 18 unscoped templates/iam.role.child.account.cfn.yaml Holds
2 managed policies, 2 roles same Holds
74 rules, 4 critical / 24 high / 32 medium / 14 low app/rules/rulesets/*.json Holds
11 services covered same Holds
No page references the deleted audit template grep across user-docs/ One row in SECURITY.md, now removed

How it was tested

Documentation only; no application code touched.

  • Relative-link check across user-docs/ and SECURITY.md — all resolve.
  • Every numeric claim in the four pages re-extracted from the CloudFormation template and the rulesets, not carried over from the previous version.
  • Confirmed no remaining references to templates/iam.role.audit.account.cfn.yaml or templates/sync.sh, both deleted by Delete the audit CFN template that defaults to the vendor's AWS account #107.

Quality gate

  • Acceptance criteria are met — the drift is corrected and the rest verified
  • Solves the user problem simply — two edits, no restructuring
  • Follows the practices in docs/practices/
  • Tests written and passing — none. Documentation only
  • Documentation updated — this PR is the update
  • No obvious performance issues — n/a
  • Ready for production — the pages are accurate against develop as of this commit

Practices check

  • Security — no secrets. The SECURITY.md change makes the known-issues list accurate, which matters more than it reads

Out of scope

  • Enabling GitHub private vulnerability reporting and creating security@teemops.com. SECURITY.md still names two channels that do not answer yet — that is a repo settings change and a mail change, both yours.
  • Trimming the child IAM template to the permissions actually used. Still unfiled; the role grants write across eight services on behalf of features that do not exist.
  • The remaining 30 pages in the content map.

🤖 Generated with Claude Code

First real staleness check on user-docs/, three days after writing it, and
two pages had drifted. Both were claims about things that changed
underneath them, which is exactly the failure mode the source-of-truth
footers exist to catch.

The architecture page said the quick-create link carries four parameters.
It carries five: N-11 phase 2 added TopsInstallId, and the parent
subscription now only forwards messages carrying that value while the rest
land in a quarantine queue. That is a materially better story for the
audience this page is written for, so it is worth saying properly rather
than leaving a stale count.

SECURITY.md listed three known issues, two of which are now closed --
#100 shipped and #102's template is deleted. A vulnerability policy telling
researchers not to report things that are already fixed is worse than
useless: it discourages reporting a regression. #101 stays, reworded to
describe what is now in place rather than what was open when it was
written, and #109 takes the freed slot with an honest note that it is dead
permission rather than exposure.

Verified rather than assumed: the IAM permissions page still holds exactly
-- 21 inline policies, 3 resource-scoped, 18 unscoped, 2 managed, 2 roles
-- and the findings pages' 74 rules and 4/24/32/14 severity split are
unchanged. No page referenced the deleted audit template except the
SECURITY.md row now removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@kiwifellows kiwifellows added the documentation Improvements or additions to documentation label Aug 3, 2026
GitHub private vulnerability reporting is enabled on the repo -- verified
via the API rather than assumed -- and security@teemops.com is routed. Both
channels SECURITY.md names now answer, so the caveat recorded against it
comes off.

SECURITY.md itself needed no change: it was written naming both channels on
the assumption they would exist, which is now true.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@kiwifellows
kiwifellows merged commit 8dc8606 into develop Aug 3, 2026
3 checks passed
@kiwifellows
kiwifellows deleted the docs/refresh-after-n11 branch August 3, 2026 10:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant